home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl70b2.lha / tcl7.0b2 / doc / EnterFile.3 < prev    next >
Text File  |  1993-07-12  |  4KB  |  91 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/EnterFile.3,v 1.3 93/07/12 11:00:23 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_EnterFile tclc 7.0
  25. .BS
  26. .SH NAME
  27. Tcl_EnterFile, Tcl_GetOpenFile \- manipulate an interpreter's file table
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. \fBTcl_EnterFile\fR(\fIinterp, file, readable, writable\fR)
  33. .sp
  34. int
  35. \fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
  36. .SH ARGUMENTS
  37. .AS Tcl_Interp checkUsage
  38. .AP Tcl_Interp *interp in
  39. Tcl interpreter from which file is to be accessed.
  40. .AP FILE *file in
  41. Handle for file that is to become accessible in \fIinterp\fR.
  42. .AP int readable in
  43. Non-zero means \fIfile\fR was opened for reading, zero means it wasn't.
  44. .AP int writable in
  45. Non-zero means \fIfile\fR was opened for writing, zero means it wasn't.
  46. .AP char *string in
  47. String identifying file, such as \fBstdin\fR or \fBfile4\fR.
  48. .AP int write in
  49. Non-zero means the file will be used for writing, zero means it will
  50. be used for reading.
  51. .AP int checkUsage in
  52. If non-zero, then an error will be generated if the file wasn't opened
  53. for the access indicated by \fIwrite\fR.
  54. .AP FILE **filePtr out
  55. Points to word in which to store pointer to FILE structure for
  56. the file given by \fIstring\fR.
  57. .BE
  58.  
  59. .SH DESCRIPTION
  60. .PP
  61. These procedures provide access to Tcl's file naming mechanism.
  62. \fBTcl_EnterFile\fR enters an open file into Tcl's file table so
  63. that it can be accessed using Tcl commands like \fBgets\fR,
  64. \fBputs\fR, \fBseek\fR, and \fBclose\fR.
  65. It returns in \fIinterp->result\fR an identifier such as \fBfile4\fR
  66. that can be used to refer to the file in subsequent Tcl commands.
  67. \fBTcl_EnterFile\fR is typically used to implement new Tcl commands
  68. that open sockets, pipes, or other kinds of files not already supported
  69. by the built-in commands.
  70. .PP
  71. \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
  72. returned by the \fBopen\fR command or \fBTcl_EnterFile\fR and
  73. returns at \fI*filePtr\fR a pointer to the FILE structure for
  74. the file.
  75. The \fIwrite\fR argument indicates whether the FILE pointer will
  76. be used for reading or writing.
  77. In some cases, such as a file that connects to a pipeline of
  78. subprocesses, different FILE pointers will be returned for reading
  79. and writing.
  80. \fBTcl_GetOpenFile\fR normally returns TCL_OK.
  81. If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
  82. make any sense or \fIcheckUsage\fR was set and the file wasn't opened
  83. for the access specified by \fIwrite\fR) then TCL_ERROR is returned
  84. and \fIinterp->result\fR will contain an error message.
  85. If \fIcheckUsage\fR is zero and the file wasn't opened for the
  86. access specified by \fIwrite\fR, then the FILE pointer returned
  87. at \fI*filePtr\fR may not correspond to \fIwrite\fR.
  88.  
  89. .SH KEYWORDS
  90. file table, pipeline, read, write
  91.